<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>{insert}</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Smarty 3 Manual">
<link rel="up" href="language.builtin.functions.html" title="Chapter 7. Built-in Functions">
<link rel="prev" href="language.function.include.php.html" title="{include_php}">
<link rel="next" href="language.function.ldelim.html" title="{ldelim},{rdelim}">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">{insert}</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="language.function.include.php.html">Prev</a> </td>
<th width="60%" align="center">Chapter 7. Built-in Functions</th>
<td width="20%" align="right"> <a accesskey="n" href="language.function.ldelim.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1" title="{insert}">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="language.function.insert"></a>{insert}</h2></div></div></div>
<div class="note" title="IMPORTANT NOTICE" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">IMPORTANT NOTICE</h3>
<p>
   <code class="varname">{insert}</code> tags are deprecated from Smarty, and should not be used. Put your
   PHP logic in PHP scripts or plugin functions instead.
  </p>
</div>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
   As of Smarty 3.1 the <code class="varname">{insert}</code> tags are only available from <a class="link" href="bc.html" title="Chapter 19. SmartyBC - Backwards Compatibility Wrapper">SmartyBC</a>.
  </p>
</div>
<p>
   <code class="varname">{insert}</code> tags work much like <a class="link" href="language.function.include.html" title="{include}"><code class="varname">{include}</code></a> tags,
   except that <code class="varname">{insert}</code> tags are NOT cached when
   template <a class="link" href="caching.html" title="Chapter 15. Caching">caching</a> is enabled. They
   will be executed on every invocation of the template.
 </p>
<div class="informaltable"><table border="1">
<colgroup>
<col align="center">
<col align="center">
<col align="center">
<col align="center">
<col>
</colgroup>
<thead><tr>
<th align="center">Attribute Name</th>
<th align="center">Type</th>
<th align="center">Required</th>
<th align="center">Default</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td align="center">name</td>
<td align="center">string</td>
<td align="center">Yes</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The name of the insert function (insert_<em class="parameter"><code>name</code></em>) or insert plugin</td>
</tr>
<tr>
<td align="center">assign</td>
<td align="center">string</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The name of the template variable the output will
      be assigned to</td>
</tr>
<tr>
<td align="center">script</td>
<td align="center">string</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The name of the php script that is included before
      the insert function is called</td>
</tr>
<tr>
<td align="center">[var ...]</td>
<td align="center">[var type]</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>variable to pass to insert function</td>
</tr>
</tbody>
</table></div>
<p>
  Let's say you have a template with a banner slot at the top of
  the page. The banner can contain any mixture of HTML, images,
  flash, etc. so we can't just use a static link here, and we
  don't want this contents cached with the page. In comes the
  {insert} tag: the template knows #banner_location_id# and
  #site_id# values (gathered from a
  <a class="link" href="config.files.html" title="Chapter 9. Config Files">config file</a>), and needs to
  call a function to get the banner contents.
 </p>
<div class="example">
<a name="id377076"></a><p class="title"><b>Example 7.56. function {insert}</b></p>
<div class="example-contents"><pre class="programlisting">
{* example of fetching a banner *}
{insert name="getBanner" lid=#banner_location_id# sid=#site_id#}
{insert "getBanner" lid=#banner_location_id# sid=#site_id#} {* short-hand *}
</pre></div>
</div>
<br class="example-break"><p>
  In this example, we are using the name <span class="quote">“<span class="quote">getBanner</span>”</span> and passing the
  parameters #banner_location_id# and #site_id#. Smarty will look
  for a function named insert_getBanner() in your PHP application, passing
  the values of #banner_location_id# and #site_id# as the first argument
  in an associative array. All {insert} function names in
  your application must be prepended with "insert_" to remedy possible
  function name-space conflicts. Your insert_getBanner() function should
  do something with the passed values and return the results. These results
  are then displayed in the template in place of the {insert} tag.
  In this example, Smarty would call this function:
  insert_getBanner(array("lid" =&gt; "12345","sid" =&gt; "67890"));
   and display the returned results in place of the {insert} tag.
  </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>
   If you supply the <em class="parameter"><code>assign</code></em> attribute,
   the output of the <code class="varname">{insert}</code> tag
   will be assigned to this template variable instead of being output
   to the template.
   </p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
    Assigning the output to a template variable isn't too useful with
   <a class="link" href="variable.caching.html" title="$caching">caching</a> enabled.
   </p>
</div>
<p>
  </p>
</li>
<li class="listitem">
<p>
   If you supply the <em class="parameter"><code>script</code></em> attribute,
   this php script will be
   included (only once) before the <code class="varname">{insert}</code> function is executed. This
   is the case where the insert function may not exist yet, and a php
   script must be included first to make it work.
   </p>
<p>
   The path can be
   either absolute, or relative to
    <a class="link" href="variable.trusted.dir.html" title="$trusted_dir"><em class="parameter"><code>$trusted_dir</code></em></a>. If security is enabled, then the 
    script must be located in the <em class="parameter"><code>$trusted_dir</code></em> path of the securty policy.
    See the <a class="link" href="advanced.features.html#advanced.features.security" title="Security">Security</a> section for details.
   </p>
</li>
</ul></div>
<p>
   The Smarty object is passed as the second argument. This way you
   can reference and modify information in the Smarty object from
   within the <code class="varname">{insert}</code> function.
  </p>
<p>
   If no PHP script can be found Smarty is looking for a corresponding insert plugin.
  </p>
<div class="note" title="Technical Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Technical Note</h3>
<p>
    It is possible to have portions of the template not
    cached. If you have <a class="link" href="caching.html" title="Chapter 15. Caching">caching</a>
    turned on, <code class="varname">{insert}</code> tags will not be cached. They will run
    dynamically every time the page is created, even within cached
    pages. This works good for things like banners, polls, live
    weather, search results, user feedback areas, etc.
   </p>
</div>
<p>
    See also
  <a class="link" href="language.function.include.html" title="{include}"><code class="varname">{include}</code></a>
  </p>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="language.function.include.php.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="language.builtin.functions.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="language.function.ldelim.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">{include_php} </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> {ldelim},{rdelim}</td>
</tr>
</table>
</div>
</body>
</html>
